package org.filesort;

import java.io.*;

/**
 * Customization of (mostly) performance-specific aspects of {@link IFileSorter} implementations
 *
 * @author cheremin
 * @since 22.02.12,  17:07
 */
public interface ISorterConfiguration {
    /**
     * @return size of I/O read/write buffers (bytes) to use. Values in range [64Kb, 512Kb] usually
     *         gives optimal I/O performance.
     */
    public int ioBufferSize();

    /**
     * @return size (bytes) of run to be sorted in memory on first phase of file merge-sort. It is
     *         not strictly enforced value, but just a hint -- sorter may change it slightly to preserve
     *         record alignment or adjust performance.
     *         <p/>
     *         Must be choosen accordingly to available memory
     */
    public int runLength();

    /**
     * @return count of runs to be merged on each merge phase. Must be > 1, sure.
     *         <p/>
     *         The less runs can be merged on each phase -- the more merge phases required to do full merge.
     *         On the other side, the more runs to be merged require more disk seeks during each merge, which
     *         can slow down I/O performance. So optimal value is a compromise between this two factors.  It
     *         depends on size of I/O buffers used (not only {@link ISorterConfiguration#ioBufferSize()},
     *         but also OS internal file system cache size), which can amortize disk seeks cost, and raw I/O
     *         throughput, which can speed up merge read/write itself.
     */
    public int runsMergeInOnePass();

    /**
     * @param expectedFileSize this value is an estimation of future file size. It can be used
     *                         to choose appropriate FS partition to place file to, and/or to allocate file initially.
     * @return newly created temporary file
     */
    public File createTemporaryFile( final long expectedFileSize ) throws IOException;

}
